home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus Special 23 / AMIGAplus Sonderheft 23 (2000)(Falke)(DE)[!].iso / Tools / Packer / xad / Developer / Include / Autodocs / xadmaster.doc next >
Text File  |  1999-11-06  |  23KB  |  644 lines
  1. TABLE OF CONTENTS
  2.  
  3. xadmaster.library/--general--
  4. xadmaster.library/xadAllocObject
  5. xadmaster.library/xadConvertDates
  6. xadmaster.library/xadDiskUnArc
  7. xadmaster.library/xadFileUnArc
  8. xadmaster.library/xadFreeInfo
  9. xadmaster.library/xadFreeObject
  10. xadmaster.library/xadGetClientInfo
  11. xadmaster.library/xadGetErrorText
  12. xadmaster.library/xadGetInfo
  13. xadmaster.library/xadHookAccess
  14. xadmaster.library/xadRecogFile
  15. xadmaster.library/--tags--
  16. xadmaster.library/--data hooks--
  17.  
  18. VERSION
  19.     $VER: xadmaster.doc 1.0 (07.09.1998) by SDI
  20.  
  21. xadmaster.library/--general--                   xadmaster.library/--general--
  22.  
  23.     When unachiving a archive you need to do following steps always
  24.     1) Allocate a "struct xadArchiveInfo" with a call to
  25.        xadAllocObject(XADOBJ_ARCHIVEINFO, 0). This structure is the master
  26.        interface and must not by modified in any way. Nearly all other
  27.        functions you may use need to get the pointer this this structure.
  28.        All data is passed with tags!
  29.     1) Call xadGetInfo() to find out if the input data is archived. If it
  30.        is, the xadArchiveInfo structure is filled with lots of information.
  31.        See xadGetInfo description to see what you may read and what stuff
  32.        not. One of the input tags must be specified here.
  33.     2) For every file in a file archive or every disk call xadFileUnArc() or
  34.        xadDiskUnArc() with one tag XAD_ENTRYNUMBER set to wanted entry. One
  35.        of the output tags must be specified here. Passwords and other stuff
  36.        is additionally allowed.
  37.     3) Call xadFreeInfo() to free the stuff allocated with xadGetInfo.
  38.     4) Use xadFreeObject() to free the xadArchiveInfo structure.
  39.     Do not use one xadArchiveInfo file structure for multiple input files!
  40.     
  41.     ANY needed structure must be allocated with xadAllocObject! None of
  42.     the xadmaster structures can be allocated any other way!
  43.  
  44. xadmaster.library/xadAllocObject             xadmaster.library/xadAllocObject
  45.  
  46.     NAME
  47.         xadAllocObject - Allocate memory for all xad related structures
  48.  
  49.     SYNOPSIS
  50.         ptr = xadAllocObjectA(type, tags)
  51.         D0                    D0    A0
  52.  
  53.         APTR xadAllocObjectA(ULONG, struct TagItem *)
  54.  
  55.         ptr = xadAllocObject(type, tag1, ...)
  56.  
  57.         APTR xadAllocObject(ULONG, Tag, ...)
  58.  
  59.     FUNCTION
  60.         This function allocates the memory of a needed xad related
  61.         structure and initializes it. You need to use this function to
  62.         allocate the structures. Any other way of allocating is not
  63.         allowed.
  64.  
  65.     INPUT
  66.         type    - in libraries/xadmaster.h defined XADOBJ_... types.
  67.                   For example XADOBJ_FILEINFO allocates xadFileInfo
  68.                   structure.
  69.         tags    - Pointer to an array of struct TagItem. Recognized tags: 
  70.           XAD_OBJNAMESIZE, XAD_OBJCOMMENTSIZE, XAD_OBJBLOCKENTRIES
  71.  
  72.     RESULT
  73.         ptr     - Pointer to required structure or 0 when an error occured.
  74.  
  75.     SEE ALSO
  76.         libraries/xadmaster.h, xadFreeObject(), tags section
  77.  
  78. xadmaster.library/xadConvertDates           xadmaster.library/xadConvertDates
  79.  
  80.     NAME
  81.         xadConvertDates - convert between date storage methods
  82.  
  83.     SYNOPSIS
  84.         result = xadConvertDatesA(tags)
  85.         D0                         A0
  86.  
  87.     LONG xadConvertDates(struct TagItem *)
  88.  
  89.         result = xadConvertDates(tag1, ...)
  90.  
  91.     LONG xadConvertDates(Tag, ...)
  92.  
  93.     FUNCTION
  94.     This function can be used to transfrom date and time between
  95.     different storage systems. One of the input tags must be specified.
  96.     Output tags may be specified multiple. The date information is
  97.     based on Gregorian calendar. Some systems can store a wider range
  98.     of dates than others. If a date produces an overflow or an
  99.     underflow for a special date, the highest/lowest valid date is used
  100.     (e.g. for timevalues 0x00000000 or 0xFFFFFFFF).
  101.     The UNIXUTC date needs locale.library to get the offset to local
  102.     time. If locale.library cannot be opened the offset is set to 0.
  103.     XAD_DATECURRENTTIME can be used to get the current system date and
  104.     time.
  105.     WeekDay information is ignored for input and always recalculated.
  106.     The calculation routines use full range of available variable space,
  107.     so f.e. a Unix date 1.1.1970 00:00:00 (value 0x00000000) with a
  108.     UTC offset of -30 min produces 31.12.1968 23:30:00.
  109.  
  110.     INPUT
  111.     ai    - the master communication structure
  112.         tags    - Pointer to an array of struct TagItem. Recognized tags: 
  113.           XAD_DATEUNIXUTC, XAD_DATEAMIGA, XAD_DATEDATESTAMP,
  114.               XAD_DATEXADDATE, XAD_DATECLOCKDATA, XAD_DATECURRENTTIME,
  115.               XAD_GETDATEUNIXUTC, XAD_GETDATEAMIGA,
  116.               XAD_GETDATEDATESTAMP, XAD_GETDATEXADDATE,
  117.               XAD_GETDATECLOCKDATA
  118.  
  119.     RESULT
  120.         result    - any of the XADERR codes or zero when all is ok.
  121.  
  122.     SEE ALSO
  123.         libraries/xadmaster.h, tags section
  124.  
  125. xadmaster.library/xadDiskUnArc                 xadmaster.library/xadDiskUnArc
  126.  
  127.     NAME
  128.         xadDiskUnArc - the master function for unarchiving disks
  129.  
  130.     SYNOPSIS
  131.         result = xadDiskUnArcA(ai, tags)
  132.         D0                    A0   A1
  133.  
  134.     LONG xadDiskUnArc(struct xadArchiveInfo *, struct TagItem *)
  135.  
  136.         result = xadDiskUnArc(ai, tag1, ...)
  137.  
  138.     LONG xadDiskUnArc(struct xadArchiveInfo *, Tag, ...)
  139.  
  140.     FUNCTION
  141.     This function dearchives a disk archive. It can be called after
  142.     a succesful call to xadGetInfo. At least the tag XAD_ENTRYNUMBER
  143.     and one of the output tags needs to be supplied. When a progress
  144.     hook is supplied, this can be used for questioning for overwriting
  145.     and ignoring of drive geometry and for status displays.
  146.     Normally disk archivers will have only one entry, but there may
  147.     be multiple disk archives.
  148.  
  149.     INPUT
  150.     ai    - the master communication structure
  151.         tags    - Pointer to an array of struct TagItem. Recognized tags: 
  152.                 XAD_ENTRYNUMBER, XAD_OUTFILEHANDLE, XAD_OUTFILENAME,
  153.           XAD_OUTHOOK, XAD_OUTMEMORY, XAD_OUTSIZE, XAD_OVERWRITE,
  154.           XAD_PROGRESSHOOK, XAD_IGNOREGEOMETRY, XAD_HIGHCYLINDER,
  155.           XAD_LOWCYLINDER, XAD_OUTDEVICE, XAD_PASSWORD
  156.  
  157.  
  158.     RESULT
  159.         result    - any of the XADERR codes or zero when all is ok.
  160.  
  161.     SEE ALSO
  162.         libraries/xadmaster.h, xadFileUnArc(), xadGetInfo(), tags section
  163.  
  164. xadmaster.library/xadFileUnArc                 xadmaster.library/xadFileUnArc
  165.  
  166.     NAME
  167.         xadFileUnArc - the master function for unarchiving disks
  168.  
  169.     SYNOPSIS
  170.         result = xadFileUnArcA(ai, tags)
  171.         D0                    A0   A1
  172.  
  173.     LONG xadFileUnArc(struct xadArchiveInfo *, struct TagItem *)
  174.  
  175.         result = xadFileUnArc(ai, tag1, ...)
  176.  
  177.     LONG xadFileUnArc(struct xadArchiveInfo *, Tag, ...)
  178.  
  179.     FUNCTION
  180.     This function dearchives a file archive entry. It can be called
  181.     after a succesful call to xadGetInfo. At least the tag
  182.     XAD_ENTRYNUMBER and one of the output tags needs to be supplied.
  183.     When a progress hook is supplied, this can be used for questioning
  184.     for overwriting and for status displays.
  185.     This function needs to be called for every file, which should be
  186.     unarchived. Best is to do unarchiving in direction giving by
  187.     info structure, because some archivers crunch multiple files in one
  188.     pass and the unarchiver needs to compress and buffer the whole
  189.     pass to get one file.
  190.  
  191.     INPUT
  192.     ai    - the master communication structure
  193.         tags    - Pointer to an array of struct TagItem. Recognized tags: 
  194.                 XAD_ENTRYNUMBER, XAD_OUTFILEHANDLE, XAD_OUTFILENAME,
  195.           XAD_OUTHOOK, XAD_OUTMEMORY, XAD_OUTSIZE, XAD_OVERWRITE,
  196.           XAD_PROGRESSHOOK, XAD_PASSWORD
  197.  
  198.     RESULT
  199.         result    - any of the XADERR codes or zero when all is ok.
  200.  
  201.     SEE ALSO
  202.         libraries/xadmaster.h, xadDiskUnArc(), xadGetInfo(), tags section
  203.  
  204. xadmaster.library/xadFreeInfo                   xadmaster.library/xadFreeInfo
  205.  
  206.     NAME
  207.         xadFreeInfo - free stuff built and allocated with xadGetInfo()
  208.  
  209.     SYNOPSIS
  210.         xadFreeInfo(ai)
  211.                     A0
  212.  
  213.         void xadFreeInfo(struct xadArchiveInfo *)
  214.  
  215.     FUNCTION
  216.         Frees all the stuff built and allocated by a call to xadGetInfo().
  217.     You always need to call this after your work with a certain input
  218.     file is finished.
  219.  
  220.     INPUTS
  221.         ai    - the master communication structure
  222.  
  223.     SEE ALSO
  224.         libraries/xadmaster.h, xadGetInfo(), tags section
  225.  
  226.